Verified docs/DATABASE_SCHEMA.md table by table against the local
database (which matches cloud — see below) and fixed what was wrong.

lib/database.types.ts needed no change: regenerating it from the local
DB produces a byte-identical file apart from the __InternalSupabase
header that `--linked` adds. Local migrations, cloud schema and the
committed types are all in sync.

Columns that did not exist as documented (each one silently breaks a
query or a .rpc() call):

- enrollments: still listed product_id/subscription_id and their CHECK
  constraint, all dropped by the entitlements migration. entitlements
  itself was absent from the doc entirely despite being the source of
  truth for course access.
- plans: documented `name`, `interval`, `stripe_*_id`; actually
  plan_name, duration_in_days, provider_*_id.
- subscriptions: documented `status`, `stripe_subscription_id`,
  `created_at`; actually subscription_status, provider_subscription_id,
  created.
- exercise_completions: documented student_id + submission/is_correct/
  ai_feedback; actually user_id + completed_by/score.
- exercises: documented initial_code/solution_code/test_cases — none
  exist.
- products: documented stripe_product_id/stripe_price_id; actually
  provider_*_id.
- exam_questions: documented a `sequence` column that does not exist.
- exam_submissions: documented is_reviewed; actually review_status.
- gamification: documented 12 tables including gamification_daily_caps
  and gamification_challenges, neither of which exists. There are 10.
- transactions: documented one composite unique index; there are three
  (product-shaped, plan-shaped, provider_charge_id idempotency).
- currency_type: documented usd/eur; there are eight values.
- RPCs: handle_new_subscription is missing _start_date,
  save_exam_feedback takes nine p_-prefixed args not six, award_xp's
  signature was wrong in CLAUDE.md and AI_AGENT_GUIDE.md.
- Table count was "65+" everywhere; it is 116.

Also adds what the doc had no way to keep right on its own:

- "Verifying this document" — the diff/introspection commands to check
  any claim here against the database in one line.
- "Tables without tenant_id" — the full 55-table list plus the query
  that regenerates it. Filtering these by tenant_id errors the whole
  query, which is a recurring source of blank pages.
- docs/README.md rewritten: it indexed six files that do not exist
  (API_ROUTES.md, RLS_POLICIES.md, four features/*.md) and advertised
  the project as "Phase 5 complete, Phase 6 next".
- docs/ACTUAL_SCHEMA.md now carries a stale banner — it claims to be
  the actual live schema and is the first thing a name-search finds,
  but it is a February 2026 snapshot documenting dropped columns.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01853LDokPbhv9Kg9Ctz9DB5